.. _example-database-02:

02 - Phreeqc Relationships
==========================

A thermodynamic database is a flat file of reactions, and it is hard to see
the shape of one by reading it. This example turns ``phreeqc.dat`` into
tables and then draws them, so that the question "what is actually in here,
and how much of it belongs to each element?" has a picture as an answer.

Nothing is simulated. A *PHREEQC Database Study* reads the database and
exposes its contents as ordinary results, which means a database can be
queried, filtered and plotted with the same tools as the output of a model
run.


The hierarchy
-------------

The study's *Relationships* table puts each element at the root and, beneath
it, every species and phase that contains it.

A species belongs to as many elements as it has, so a species with three
elements appears under three roots. That is a deliberate property, not double
counting: the question being asked is "what does this element participate
in?", and the answer for CaHCO3+ is that it is part of the calcium chemistry
*and* the carbon chemistry *and* the hydrogen chemistry at the same time.
Read the sizes as reach, not as a partition.


The plots
---------

Both plots draw the same hierarchy; they are worth having side by side
because the two shapes answer different questions.

.. figure:: Sunburst.svg
   :alt: Sunburst of phreeqc.dat, elements at the centre and their species and phases around them
   :align: center

   The sunburst: elements in the inner ring, their species and phases in the
   outer one. H and O take the largest slices by far, since nearly every
   species in an aqueous database contains one or both -- which is the shape
   of water chemistry rather than a quirk of this database. The metals'
   slices are the useful part: they show at a glance which elements
   ``phreeqc.dat`` describes richly and which it barely describes at all.

.. figure:: TreeMap.svg
   :alt: Treemap of the same hierarchy, areas proportional to the number of species
   :align: center

   The same hierarchy as a treemap. Area is easier to compare than angle, so
   this is the one to read quantitatively; the sunburst is the one to read
   for structure.


What it is for
--------------

Knowing the shape of a database is how you form an expectation before a run,
and expectations are what make a wrong answer visible. An element with three
species in the database will not produce rich speciation no matter what the
water contains.

:ref:`example-database-01` asks the same kind of question across six
databases at once, and :ref:`example-database-03` compares the constants
themselves.


Source
------

* Parkhurst, D. L. and Appelo, C. A. J. (2013). *Description of input and
  examples for PHREEQC version 3.* U.S. Geological Survey Techniques and
  Methods, book 6, chapter A43. ``phreeqc.dat`` is PHREEQC's default
  database, distributed with it.